From afaa275dc86b12c2844c60c079c46454cb21471c Mon Sep 17 00:00:00 2001 From: Michael Catanzaro Date: Thu, 7 Jan 2021 11:30:57 -0600 Subject: [PATCH] gtkbuilder: fix recommendations that no longer make sense in GTK 4 In GTK 3, it was pretty much always better to use gtk_builder_new_from_whatever() rather than gtk_builder_add_from_whatever(). But in GTK 4, this is no longer generally true. Let's add some context on when you want to use one or the other. --- gtk/gtkbuilder.c | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c index ef1237fccc..d3edc4d0da 100644 --- a/gtk/gtkbuilder.c +++ b/gtk/gtkbuilder.c @@ -1153,9 +1153,6 @@ gtk_builder_create_bindings (GtkBuilder *builder, * or gtk_builder_add_from_string() in order to merge multiple UI * descriptions into a single builder. * - * Most users will probably want to use gtk_builder_new_from_file(), - * gtk_builder_new_from_resource() or gtk_builder_new_from_string(). - * * Returns: a new (empty) #GtkBuilder object **/ GtkBuilder * @@ -1173,7 +1170,9 @@ gtk_builder_new (void) * Parses a file containing a [GtkBuilder UI definition][BUILDER-UI] * and merges it with the current contents of @builder. * - * Most users will probably want to use gtk_builder_new_from_file(). + * This function is useful if you need to call gtk_builder_set_current_object() + * to add user data to callbacks before loading GtkBuilder UI. + * Otherwise, you probably want gtk_builder_new_from_file() instead. * * If an error occurs, 0 will be returned and @error will be assigned a * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR @@ -1367,7 +1366,9 @@ gtk_builder_extend_with_template (GtkBuilder *builder, * Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI] * and merges it with the current contents of @builder. * - * Most users will probably want to use gtk_builder_new_from_resource(). + * This function is useful if you need to call gtk_builder_set_current_object() + * to add user data to callbacks before loading GtkBuilder UI. + * Otherwise, you probably want gtk_builder_new_from_resource() instead. * * If an error occurs, 0 will be returned and @error will be assigned a * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_RESOURCE_ERROR @@ -1517,7 +1518,9 @@ gtk_builder_add_objects_from_resource (GtkBuilder *builder, * Parses a string containing a [GtkBuilder UI definition][BUILDER-UI] * and merges it with the current contents of @builder. * - * Most users will probably want to use gtk_builder_new_from_string(). + * This function is useful if you need to call gtk_builder_set_current_object() + * to add user data to callbacks before loading GtkBuilder UI. + * Otherwise, you probably want gtk_builder_new_from_string() instead. * * Upon errors %FALSE will be returned and @error will be assigned a * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or -- 2.30.2